package com.ai.plug.core.annotation;


import com.ai.plug.core.spec.callback.tool.DefaultMcpCallToolResultConverter;
import com.ai.plug.core.spec.callback.tool.McpCallToolResultConverter;

import java.lang.annotation.*;

/**
 * Marks a method as a MCP Tool.
 * @author han
 * @time 2025/6/25 10:14
 */
@Target({ ElementType.METHOD, ElementType.ANNOTATION_TYPE })
/**
 * 指定该注解在运行时保留，以便通过反射机制获取注解信息
 */
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface McpTool {

    /**
     * 工具的唯一标识符。如果未提供，则使用方法名作为标识符。
     */
    String name() default "";

    /**
     * 工具的可选人类可读名称，用于显示目的。
     */
    String title() default "";

    /**
     * 工具的描述信息。如果未提供，则使用方法名作为描述。
     */
    String description() default "";

    /**
     * inputSchema: 定义预期参数的 JSON Schema
     * outputSchema: 可选的定义预期输出结构的 JSON Schema
     * annotations: 描述工具行为的可选属性
     */
    String mineType() default "";

    /**
     * 如果为 true，表示该工具不会修改其运行环境
     */
    boolean readOnlyHint() default false;

    /**
     * 如果为 true，表示该工具可能执行破坏性更新操作
     */
    boolean destructiveHint() default false;

    /**
     * 如果为 true，表示使用相同参数重复调用该工具不会产生额外效果
     */
    boolean idempotentHint() default false;

    /**
     * 如果为 true，表示使用相同参数重复调用该工具不会产生额外效果（开放世界假设）
     */
    boolean openWorldHint() default false;

    /**
     * 如果为 true，表示该工具与外部实体进行交互
     */
    boolean returnDirect() default false;

    /**
     * 用于将工具输出转换为 CallToolResult 的转换器类
     */
    Class<? extends McpCallToolResultConverter> converter() default DefaultMcpCallToolResultConverter.class;
}
